home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-19
/
quikcmd3.zip
/
BUZ.DOC
< prev
next >
Wrap
Text File
|
1992-07-05
|
48KB
|
987 lines
BUZ.EXE Version 1.10 completed in May 1992
~* BUZ.EXE V1.10 Self-Indexing View/Print Utility for Text Files
~ By Dan Jincks (C) 1991, 92
All Rights Reserved. Copying and distribution of BUZ.EXE and BUZ.DOC
are specifically limited to the terms and conditions contained in
BUZ.DOC. Any copying and distribution of BUZ.EXE and BUZ.DOC, other
then that which is specified in BUZ.DOC, requires the written permission
of Dan Jincks, the author. Shareware distribution is specifically
limited to the United States and Canada.
Version 1.00 was not released to the general public. A number of copies
were given out to individuals, and who knows who they gave them to, etc.
To be sure that a distinction exits, the first true general release is
called BUZ.EXE Version 1.10 rather than 1.00. It differs from Version
1.00 in that it is faster, smaller (but documentation got larger), and
is more versatile in the print capabilities. It also has less bugs and
more error trapping. The Quick Index left extension character was
changed from a tilde to a right curly bracket. The Quick Index format
was changed to make them faster and use less disk space.
~* Introduction
---------------
BUZ was created to allow standard ASCII text files to serve as "Soft
Publications". It automatically detects a "prepared for BUZ" text file and
creates an index table "front end" as it begins running. Pressing an
associated key in the displayed index table, sends the file viewer directly
to that location within the text file. A single key press returns you to
the index table, from any location in the file. The file viewer features
full up/down scrolling abilities, by page or by line. The only preparation
required to a convert a standard ASCII text file, is the simple insertion
of tilde ~ characters at the beginning of lines to be referenced by the
index table. BUZ automatically highlights lines in the text file that were
marked by a tilde. Selective highlighting in the index table is available
to aid in defining main and sub sections. BUZ can also be used to view
ordinary ASCII text files. Files without index markers are presented
without the index table. BUZ is also specially designed to allow indexed
viewing of Basic, Assembler, Lisp, Pascal and "C" ASCII source code. In
source code modes it auto-indexes with reference to any comment lines that
begin in the first character position of a line.
In addition to the viewer capabilities of BUZ, it contains considerable
versatility for printing out text files. Printing can be sent to any LPT
or COM port, or to a file. Any ASCII file can easily be completely or
partially printed out. Partial printout definition is set up to bear
relation to the position in the file as it is being viewed. You can easily
print out just that portion of a large text file that you need. Automatic
headers and page breaks, with user defined titles, are available for any
printing task. Page definitions are automatically created by how you
specify each printout, so there is no need to "printer-page format" any
text files that will be printed by BUZ. If you need a text file
"printer-page formatted" for some reason, BUZ can do that for you as well -
in seconds. Since BUZ can handle extremely large text files, partial
print-to-file techniques can quickly break up unwieldy files for loading
into limited capacity text editors. Custom indentation, page lengths, and
line lengths are supported as well. Considerable file information is also
presented and updated by option settings.
~ Requirements, Statistics and General Information
---------------------------------------------------
Requirements:
IBM PC Compatible Computer with 256k of available free memory.
MS-DOS or PC-DOS 3.0 or later.
Display adapter: Any that can display 80 character X 25 line text
screens. (Mono, Herc, CGA, EGA, VGA)
For formatted printouts: Any printer with at least 80 character/line
capabilities
Statistics and General Information:
Maximum size text file: 32,716 lines (typically well over 1 megabyte)
Maximum number of Index entries in a file: 360
Speed: Initial startup varies, depending on the system and size of the
file. Capable of creating an associated Quick Index file to
reduce startup time for individual files. Once the initial
startup has completed, file access is virtually instantaneous for
any size file located on hard drive systems.
Type of viewer: Reads directly from disk files, will not alter the
file. Highly disk oriented, so the best performance is on a hard
drive.
Types of files that can be viewed: Standard ASCII text, "Index
Prepared" Standard ASCII text, ASCII source code.
Source Programming Language of BUZ.EXE: Microsoft (tm) BASIC
Author of BUZ.EXE and BUZ.DOC: Dan Jincks
HCR 77, Box 155A
Annapolis, MO 63620 USA
Type of distribution allowed: As Shareware in USA and Canada only.
Availability of source code: Not generally available - Contact the
Author.
~ Command line Syntax for using BUZ.EXE
----------------------------------------
Usage: BUZ [path]filename [/MSB | /C | /AL | /PAS] [/M | /AC] [/LS]
BUZ or BUZ /? for syntax
filename - The filename of an ASCII file to be viewed by BUZ. It
must be ASCII text, free of non-standard control codes.
BUZ can handle any size file up to 32,716 lines long.
/MSB - Causes BUZ to use the ' single quote character for creating its
index for the file being viewed. The single quote is typically
used for comments in Microsoft BASIC (and Quick BASIC source
code.
/C - The / slash character is used for indexing - used for comment
lines in "C" source code.
/AL - The ; semicolon character is used for indexing - used for
comment lines in Assembler and Lisp source code.
/PAS - The { left curly bracket character is used for indexing - used
for comment lines in Pascal source code.
Note: By default, BUZ uses the ~ tilde character for creating its
index. No matter which character is specified, it must be the
very first character in a line, without any leading spaces, to
be recognized as an index marker.
/M - Causes BUZ to display in Monochrome.
/AC - Causes BUZ to display in an alternate color scheme.
/LS - Causes BUZ to Leave the viewing Screen intact when you quit.
When you quit while in the viewer, the current screen of
information remains when you return to the DOS prompt. If you
are in the index screen when you quit, a normal exit occurs.
Examples:
BUZ BUZ.DOC
To view BUZ.DOC in the default index and color modes.
BUZ BUZ.DOC /M
To view BUZ.DOC in monochrome.
BUZ C:\BASIC\PROGRAM.BAS /MSB /AC
To view a Microsoft BASIC source code file named PROGRAM.BAS in the BASIC
subdirectory using the alternate color scheme.
BUZ BUZ.DOC /LS
To view BUZ.DOC and leave your final view of it on the screen when you
return to the DOS prompt.
~ Getting the Best Performance from BUZ
----------------------------------------
BUZ.EXE was designed to handle very large text files. The larger that
a file is, the more likely it is that you may notice BUZ slowing down a
bit. To get the best speed out of BUZ, certain factors can help
considerably.
1. Be sure that the file being read is located on a hard drive. (Of course
a RAM drive is even faster.) The performance of BUZ is greatly
affected by disk access speed, so reading a file from a floppy disk is
the surest way to reduce its overall performance.
2. If all of the lines in the file are 76 characters or shorter, the
scrolling response speed is greatly increased, particularly when the
text file is very large (over 8000 lines).
3. If the file is free of imbedded Form Feed and Tab characters, scrolling
speed is slightly faster.
4. Creating a "BUZ Quick Index" file will greatly reduce the start up
time for future viewings of any "indexed" text or source code files.
All of the above are optional but are well worth the effort if the file is
large and/or a slower computer/drive will be used to view the file. The
"Printing Definition" screen can provide instant information about #2 and
#3 considerations listed above. Start by viewing the file, then press "P"
to get the printing screen. It reports the length of the longest line in
the file, and if it contains any Form Feed or Tab characters. You do not
need to print anything to view this screen. By printing-to-a-file you can
create a duplicate file without Form Feed characters. If you set the
"Tab #" before printing-to-a-file, Tab characters will be replaced by
spaces (see the section about "Tab #"). Long lines however, will require
you to use a text editor. BUZ cannot reformat or edit text files. After
#2 and #3 are dealt with as you intend to, then create a BUZ Quick Index
file if you can spare some disk space. See the "Quick Index" section.
~* Using the BUZ File Viewer
----------------------------
When BUZ reads a file it automatically determines whether index markers are
present. If the file has been marked, you will see the index table being
built as it reads the file. If BUZ cannot find a marker on the first
screen page, it will display the message "Reading File" until it completes
its initial start-up. (It will also display "Reading File" if it is reading
a BUZ Quick Index file.) The length of time required by the start-up
process is proportional to the length of the file that you are viewing.
The longer the file, the longer the start-up time. Once the start-up is
complete, BUZ can move around in the file very quickly if the file is on a
hard drive. Floppy disk files will greatly increase the viewer access
time. This is because the drive quits running after a short time and must
restart when BUZ looks for a new location in the file. BUZ does not load
any of the file into RAM. It only keeps records of locations in the file
in RAM. This allows reading and moving around quickly in very large files
(well over the basic DOS RAM limitations), but makes floppy disk
performance sluggish. BUZ was designed primarily for hard drive systems
and large text files, but will function fully on floppy drives - although
much slower.
The initial user interface screen and controls will depend on whether the
file was indexed. If the file was indexed, you will begin with the "Index
Page" screen(s). If the file was not indexed, you will begin at the top of
the file or "Home" screen of the scrolling viewer.
No matter which screen you are in, the very top line is for relevant
information and the very bottom line lists your key press options. Look up
to see what is happening. Look down to see what you can do.
~ The Index Screens
--------------------
When a file is "prepared for BUZ", the initial user interface are the index
page screens. They are an active index to jump directly to various places
within the text file. This is the equivalent of the table of contents in a
book. You will be presented with a list of subjects (sections) to choose
from. All that is required, is to press the listed letter key to go
directly to that place in the text file. If the index is longer than 18
sections, you can page through the index by using either Page Up - Page
Down keys or by pressing the space bar. You may also go directly to the
END or top (HOME) of the file, directly from the index.
After pressing an index selection, you will begin viewing within the text
file at the desired location. From there, the normal scrolling viewer is
functioning. To return to the index from anywhere in the text file, just
press the space bar. Once back at the index screens, you can jump directly
to another location in the file as desired.
~ The Scrolling File Viewer
----------------------------
The scrolling file viewer provides full up-down file viewing capabilities.
You can go up or down in the text file by one line at a time or one entire
screen page at a time. Simply use the cursor keys, Page Up-Down keys,
Home, or End keys to navigate. Three other optional actions are also
available while using the scrolling file viewer:
~ Tab#
----------
By pressing the "T" key you can redefine the number of spaces that are
substituted for any ^I tab characters in the file that you are viewing.
The default is to use the DOS standard, 8 space expansion on 8 character
intervals. For most files this is correct. Some text editors (most
notably programming source code editors) allow custom definition of tab
expansion. If the column alignments don't look correct, or there are
excessive leading spaces in some lines, you may want to try redefining the
tab expansion. This doesn't actually alter the original file, but will
affect the appearance of the file on both the screen and any printouts.
The effect of this tab setting has no interval definition. It merely
substitutes a given number of spaces for each ^I tab character. This works
fine for leading tabs, but not for mid-line tabs. Ideally text files
should not contain ^I tabs, unless they conform to the DOS standard.
The "Printing Definition Screen" has an alert that a file contains Tabs or
Form Feed characters. Press "P" while in the file viewer to check that
alert message, if you suspect that Tabs may be causing problems in a file.
Note: The <T=Tab#> option does not appear as a listed option when the file
viewer is entered from the index, but it is still available by pressing the
"T" key.
~ Shell
-----------
While using the BUZ file viewer, you can press the "S" key to "Shell" to
the DOS command line. You are not actually quitting BUZ, but freezing its
actions and place while allowing you to return to DOS. BUZ and your place
in the file being viewed are still in your computers memory. When you type
"EXIT" at the DOS command line, you will return to BUZ in the place that
you were before you shelled.
The shell feature was included to allow you to "hold your place" and do
something else - and then pick up where you left off. A use for this might
be to try something on your computer that you are reading documentation
about. Another use might be to hold your place and look up your
appointments or a phone number. You can even run BUZ a second time on
another file.
When you shell, BUZ will report how much free memory is remaining to run
other programs. Since BUZ is still in memory, you will have less
available. To regain all of your free memory again you must "Quit" BUZ,
rather than use the shell option.
BUZ records the drive and directory that you were in when you used Shell.
You can freely change drives and directories, while back at the DOS command
line, for whatever you need to do. When you enter the EXIT command to
return to BUZ, it automatically returns to its starting drive and
directory. Shell cannot be used to change the directory that BUZ is
currently functioning within.
~ Print
-----------
By pressing the "P" key you bring up the printing definition screen.
This screen provides information and choices that allow you to print part
or all of the file that you are currently viewing. Printing does not occur
by simply pressing the "P" key, so feel free to explore this option without
worry of wasting your paper and ribbon.
~* Printing Definition Screen
-----------------------------------
BUZ allows a great deal of versatility for printing out text files. Its
main emphasis is on allowing partial printouts of large files. For this
reason the "printing definition screen" may appear a bit complicated at
first. Don't hesitate to explore the available options since you can abort
back to the viewer instantly. As a matter of fact, the "printing
definition screen" contains a lot of useful information about the file
that you are viewing. The top 1/3 of the screen contains information about
the file size and just where you were currently located when you pressed
the "P" key in the file viewer. It also provides information about line
length and some existing control codes.
The center 1/3 of the screen is a list of option keys that you can use in
various ways to set up the definition of your printout. Feel free to
experiment with their settings, without actually starting a printout. It
will not start printing without a confirmation from you. Even with a blind
confirmation, the default is to print out only 1 page - you must choose
an option to be able to print more then 1 page.
The bottom 1/3 of the screen (inside of the box), is the active definition
for your printout. It is a summary of the parameters for the printout.
Any input requests will also occur in this box (except for the title).
Below are your option keys for defining the printout:
~ Complete File
-------------------------
Pressing the "A" key specifies the entire file from beginning to end.
~ Current Top Line to End
-----------------------------------
Pressing the "B" key specifies printing the top line of the screen to
the end of the file. "Current Top Line" refers to the line at the top of
the file viewer screen when you pressed the "P" key for the print option.
~ Current Section
---------------------------
Pressing the "C" key sets the printing definition to print that section of
an indexed file that you were viewing when you entered the "printing
definition screen". It begins at the index marked line and ends with the
line before the next index marker in the file. The "current section" title
appears above and you should check that it is what you actually wish to
printout. If more than one index marked section was on the screen at the
time that you chose "print", the last one on the screen is treated as the
current section. The "D _ Down one section" and "U _ Up one section"
options allow you to adjust the "current section" by one index marked
section.
If the file being viewed contains no section definitions, neither the
option keys nor the section information will appear in the printing
definition screen.
~ Change Printer Port
-------------------------------
The "P" key is a selector key to specify where the printing output is to be
sent. The "Printing to:" setting in the definition box changes each time
that the "P" key is pressed. You can send your printout to LPT1, LPT2,
LPT3, COM1, COM2, COM3, COM4, or to a FILE. The default setting is LPT1.
Be sure that any LPT or COM specification is actually a printer, or you may
cause an error to BUZ (and DOS) that will land you back on the DOS command
line!
The "print to a file" capability of BUZ may at first seem redundant, but
it is actually a very versatile option. Specifying a portion of a large
file can allow you to clip out a portion for a text editor with limited
capacity. When you "print to a file" the tilde markers are automatically
striped out. You have the option to print with headers and page breaks, so
you can instantly create a "printer page formatted" file if you have a need
for one. A few things to keep in mind about the "print to a file" option:
1. All tilde markers are normally striped out. ONLY tilde markers are
striped out. Any /MSB, /C, /AL, /PAS comment based markers are NOT
removed. (Note: To preserve the tilde markers in a normal "prepared
for BUZ" file, load the file using the /AL command line option. Also
be sure that "Indent" is set to zero.)
2. All pre-existing form feed characters in the file are striped out.
3. If the text was shifted to the right on the screen, check to see if
"Indent" is set at 3 by default. BUZ automatically indents suitable
files (ones that have no lines over 76 characters in length) by 3
spaces. Use the "Indent" setting to adjust if needed.
4. Printer page formatting with headers and page breaks is set for
standard 66 line by 80 character pages by default. The headers will be
just like a standard BUZ printout. Since each BUZ printed page ends
with a FormFeed, "Lines per Page" can be used to control the amount of
blank lines left at the end of each page. A smaller number yields more
blank lines.
5. Any "TAB#" setting that is in effect, will be reflected in the "print
to a file" output. (You can use this feature to strip or replace ^I
tabs with spaces in some files.)
6. Any line wraps from line lengths over 80 characters, will not be "hard
wraps" in the output file. They will still be their original length.
~ Wrap Tracking for 80
--------------------------------
When Wrap Tracking 80 is [Yes], BUZ will count any lines over 80 characters
as 2 lines to keep the page lengths corrected. It takes into account the
"Indent" value as well. It also prevents the header from wrapping if you
"Indent" beyond 5. If you are printing on an 80 character/line printer,
leave "Wrap Tracking 80" set to [Yes]. If you are printing in condensed
mode (132 or 160 character lines) or on a wide printer, set Wrap Tracking
80 to [No]. Condensed mode and Wrap Tracking 80 [No], is the best way to
print files that have lines over 80 characters. The "Max. Line Length"
plus the "Indent" setting will indicate the best printing approach for a
particular file. If "Max. Line Length" + "Indent" exceeds 80, then some
lines WILL wrap on 80 character/line printers. The "Max. Line Length"
value is the length of the longest line found in the file.
~ Specify the Top Line
--------------------------------
Pressing the "1" option allows you directly input the line number of the
file where the printout is to begin.
~ Specify # of Lines to Print
---------------------------------------
Pressing the "2" option allows you to directly input the number of lines
(starting with the defined top line) that will be printed out.
~ Specify # of Pages to Print
---------------------------------------
Pressing the "3" option allows you to directly input the number of pages
(starting with the defined top line) that will be printed out. The "Pages"
referred to here will be defined by the "Page Formatting" and "Lines per
Page" settings that are in effect. Set the "Page Formatting" and "Lines
per Page" options before specifying the number of pages. If your file
contains long lines that "wrap", the page estimates may be under the actual
number, but the printouts WILL format out properly.
~ Left Indent
-----------------------
This setting is the number of blank spaces in front of each line that is
printed. There are two defaults: It is set to 3 if there are no lines over
76 characters in the file, or it is set to zero if the file contains any
longer lines. You can set the indent to anything that you wish, but you
should do it with caution. Printers will wrap lines that are longer then
what they can print in a single line. The wrapped portion of any line will
begin on the next line - without any indentation. If "Wrap Tracking for
80" is [Yes], BUZ will at least prevent most page overflows on 80
character/line printers. The maximum allowed Indent value is 85 when "Wrap
Tracking for 80" is [Yes].
The appearance of indented with wrapped lines is usually not very neat,
with one exception - double spaced printouts. By setting the indent to the
number of characters/line supported by your printer, you will get a neat
double spaced printout. A double spaced printout should either have "Page
Formatting" set [No] or be done as follows: 1. Be sure "Max. Line Length"
is not over 80; 2. Be sure your printer is in 80 character/line mode;
3. [Yes] for both "Page Formatting" (or [Lite]) and "Wrap Tracking 80";
4. Set the indent value to 80 (plus upto 5 if "Max. Line Length" is 75 or
less). Note: The "Pages" estimates will be 1/2 of the actual number of
printed pages when you double space using Indent.
The "Max. Line Length" value is provided to assist with indenting printouts
properly. Its value is the length of the longest line in the file. You
can therefore indent by as many spaces as your printer can handle, in
addition to the longest line. "Indent" + "Max. Line Length" should not
exceed the character/line abilities of your printer. If your printer
allows 160 and/or 132 character Condensed printing, you can set your
printer, and indent considerably. When doing printing in condensed modes
(or on wide printers) be sure to set "Wrap Tracking for 80" to [No]. (Be
aware that BUZ cannot set your printer to condensed mode nor can it detect
that it is set as such.)
The indent value affects both the text and the headers. If "Wrap Tracking
for 80" is [No], the headers are always indented as much as the text. If
"Wrap Tracking for 80" is [Yes], then the headers will only indent to 5
spaces maximum. You can indent the text further, but the headers remain at
5 to prevent them from being wrapped or cropped.
~ Page Formatting
---------------------------
"Page Formatting" [Yes], means that the output will have an informative
header on each page, and have a few blank lines at the bottom of each page.
"Page Formatting" [No], means that the output will be continuous without
any headers or page-break blank lines. When you change this setting, all
page estimate values will be adjusted accordingly. "Lines per Page", "Wrap
Tracking for 80", "Change Title" and "Left Indent" settings have relevance
to page formatting that is discussed in each section.
The headers on each page contain 5 areas of information:
1. A custom defined title that is constant on each page. See the
"Change Title" section about defining it.
2. A date is printed. This is the date (per your computer) that the
printout was made. It is not the directory date associated with the
file being printed.
3. "From line ###" Reports what line in the file that the printing
began with.
4. "p#" is the sequence page of the printout. It starts with 1 on the
first page, then 2 on the second, etc.
5. The file name that the printout originated from is printed on each
header. It is only the basic file name without any preceding path.
When "Page Formatting" is [Yes], 11 lines are used per page for the
formatting; 7 for the header, and 4 for page breaks. See the "Lines per
Page" section for variations that affect the page break spaces.
"Page Formatting" [ Lite ] is the same as [ Yes ] except that the header
contains only the Title and page number. It was included for those
printouts that you do not want much if any header, but need the page
breaks. Making the Title blank will further reduce the header to only the
page number and header base line. If you then increase the "Lines per
Page" to 68 and roll back the paper a bit, you will have an uncluttered
printout with little more than page breaks.
~ Change Title
------------------------
Any printout by BUZ can be formatted with headers and page breaks, or not.
The top line of each formatted printed page has a constant custom defined
title. By default, the file's title line is used (if there is one). If
you wish to enter a new title, press "T" and type it in using standard
editing keystrokes as needed. If you want to clear the line and start
again, press Escape. Press Enter when you are done. The title will only
be used if "Page Formatting" is [Yes] or [Lite]. The maximum number of
printable characters is 70. You can type in more than 70, but they will be
cropped off in the printout.
~ Lines per Page
--------------------------
The "Lines per Page" setting is used to define how many lines your printer
can print per page. Most tractor feed printers have 66 line pages, which
is the default setting. Sheet feed printers may have less, perhaps 60.
For the actual printout, this setting is only relevant when "Page
Formatting" is [Yes] or [Lite]. This setting is also used for the number
of page calculations that are displayed on the printing definition screen.
The "Lines per Page" setting can also be used to customize the way that
your printout will format. When the proper number of lines has been
counted by BUZ, it sends a Form Feed to your printer, and begins printing
on the next page (as defined by your printer). The Header printed by BUZ,
uses 7 lines on each defined page. Text is then printed until 4 lines are
remaining (or the end of the defined printout), and then a Form Feed is
sent. This is the default for 66 line pages. By setting "Lines per Page"
to a lower number, you can increase the number of blank lines on the end of
each page.
If you want a no-page-break printout with only one leading header, you
can set "Lines per Page" to the total number of lines to be printed - plus
11 (or more) to allow for the header and ending blank lines. The accuracy
of your setting can be confirmed by checking that the "# of Pages:"
indicates just 1.
If you can very accurately align the pages on your printer, you can set it
to 68 and save an occasional sheet of paper. Don't set for less then 2
ending blank lines per page, since BUZ may print an extra line under some
circumstances. If a page overflow occurs, there will be blank pages and/or
pages that are only partially filled.
~ Filename for Output
----------------------------
If you are printing-to-a-file, the final question will be to provide a
filename. The top of your screen will become a directory listing of your
current directory and drive. The filename that you supply can be preceded
by a path specifying a different directory, but you will not be able to
preview the contents of that directory. If the filename that you enter
already exists, you will be asked if it is alright to overwrite it or not.
If you answer "N" no, the print-to-a-file will be aborted.
~* Creating a "Prepared for BUZ" Text File
------------------------------------------
Preparing an existing text file for indexed viewing is extremely simple.
All that needs to be done is to insert a tilde ~ character into the first
character position of lines that are to be used as index markers. It is
important that the tilde character be the very first character. If a space
or other character precedes it in the line, it will not be interpreted as a
marker. Since BUZ has no editing capabilities, you will need to use a text
editor to insert the tilde markers. If you use a word processor, be sure
that it is used in the ASCII mode, so that its document mode formatting and
control codes are not embedded into the file.
The first 2 lines marked by a tilde are for the title and author credits.
They are used only for display purposes, and are not actually placed into
the index list. If you do not want a title or author line, place the first
2 tilde markers on leading blank lines.
The third tilde marker is the first actual index marker. All tilde marked
lines, beginning with the third, will be included into the index table as
reference lines. Any number of tilde marked lines are allowed - up to the
maximum of 360 (20 index screen pages). Any tilde marked lines exceeding
the maximum are ignored by BUZ. The marked lines appear in the index table
in same order that they are in the file - from top to bottom. Typically
the marked lines would be chapter or section titles, but any line can be
marked for index use. Note that the entire marked line appears in the
index, so marked lines should not exceed 75 characters in length. (They
will be cropped if they are over 75.)
When lines marked by a tilde are displayed or printed out by BUZ they will
not include the tilde itself. Leading tilde characters are striped from
the lines of text before display or printing. Of course, if a "prepared
for BUZ" file is viewed or printed by another utility, the tilde markers
will be visible. If you wish to create a copy of the prepared text file
with the tilde markers removed, just have BUZ print-to-a-file the entire
text file.
Other than the tilde insertions, there are no other special formatting
requirements for standard ASCII text files. Any file that displays
properly by using the DOS "TYPE" or "MORE" commands will generally work
well with BUZ. For best appearances, it is recommended that the line
length be limited to 75 characters (not including the tilde markers). BUZ
will wrap lines that are over 80 characters in length, but the results will
not be very appealing. Extremely long lines (over 160 characters) are
likely to cause problems for BUZ.
Embedded control codes in a text file may create problems. BUZ stripes out
any existing ^L (formfeed) codes for screen and printer output and expects
lines to end with a standard carriage return-line feed. It is not designed
to deal accurately with some control codes, such as lone ^J (line feed)
insertions. The presence of these types of codes is not always clearly
visible, but they may cause odd screen rolls by the BUZ file viewer.
Embedded ^I (tab) characters may cause problems in lines over 80 characters
long. For best results, remove any non-standard control codes from text
files intended to be viewed with BUZ.
The file viewer will accurately display all ASCII characters from decimal
#32 through #254. That includes all of the normal upper ASCII graphics
characters. Whether the graphics characters print properly, will depend on
if the printer can interpret them. Some of the ASCII characters below #32
(control codes) appear to work in the BUZ viewer, but should not be used
since they have special meanings to printers. Sending unplanned control
codes to a printer can produce all kinds of havoc in printouts.
~ Highlighting lines of text
--------------------------------
BUZ will automatically highlight any line of text that has the leading
tilde marker character. (It will do this regardless of whether the file
was intentionally "index prepared" or not.) To allow emphasis in the index
table, a tilde followed by an asterisk ~* , will cause that line to be
highlighted in both the index table and the file. The asterisk character
IS displayed on the screen and on any printouts.
~ The /MSB /C /AL and /PAS Command Line Options for Source Code
-------------------------------------------------------------------
BUZ is equipped to give indexed viewing of properly formatted source code
files for Microsoft BASIC (and Quick BASIC), "C", Assembler, Lisp (and
AutoLisp), and Pascal programming languages. Of course the desired file
must be in the original ASCII text format, not compiled or in a binary
format. When /MSB is used, BUZ ignores tilde character and indexes on the
' single quote character (the BASIC comment line character) instead. To
be a qualifying index line, the single quote must be the very first
character on that line. Any indented comment lines are not treated as
index marked lines, so it is a simple process to qualify certain comment
lines for index usage. Unlike the default tilde markers, the leading
single quote character is both displayed and printed. The /C, /AL, and
/PAS options are identical to /MSB except that the index character is
/ slash for /C, ; semicolon for /AL, and { the left curly bracket for /PAS
(the leading comment area/line characters for programming source code).
[ If you program in another language, and this feature sounds appealing -
send me a sample of source code (with some comment lines included) and I
will try to include an appropriate switch in the future. ]
Source code files typically contain lines over 80 characters. These long
lines cause BUZ to wrap them to the next screen line. This can cause some
minor aberrations in the viewer's scrolling. It is accurate in the Page
Up-Down scrolling, but the Line Up-Down scrolling can "skitter" a bit from
the wrapped lines. What is displayed on the screen is accurate, but the
wrapped lines can cause a slight jump (a few lines) in file location under
some circumstances. This slight jump is most likely to occur when changing
from using line scrolling to using page scrolling. The printouts ARE quite
accurate, with long lines being wrapped as needed. For most printouts of
source code, it is recommended that you switch your printer to condensed
mode if it has the capability. That will eliminate the wrapping of longer
lines. (See the "Wrap Tracking for 80" section.
~ Creating and Using BUZ Quick Index files
----------------------------------------------
By default BUZ creates an index on-the-fly for valid files. Creating this
index requires it to parse through every line of the file before you can
begin viewing. This can take a fair amount of time with large files. BUZ
can create a copy of the index and save it to disk and then, in future
viewings, read it instead of the entire file. The use of a BUZ Quick Index
file will typically allow you to begin viewing in 1/2 or less of the normal
startup time. (This is a hard drive speed enhancement feature. It is
disabled while reading a file on the A: or B: drives. Creating a Quick
Index on a floppy will only waste disk space.)
Creating a BUZ Quick Index is as simple a key press! While in the index
screens, press the X key and a BUZ Quick Index file will be created and
saved to disk in the same directory as the text file that you are viewing.
The BUZ Quick Index file has the same name as its associated text file
except that the first character of the extension is replaced by the right
curly bracket character "}". The next time that you view your current
file, BUZ will find the Quick Index file and read it instead of parsing the
entire file.
If you edit or change a text file that has an associated Quick Index file,
BUZ will know this and not use it. As a matter of fact, BUZ will
automatically try to delete any Quick Index that no longer matches its
associated text file. It then switches to its default of parsing through
the entire file. It is up to you to create a new Quick Index if you want
one. If you see the index table being built line-by-line, you know that
there is not a valid Quick Index being read.
If you create a BUZ Quick Index file for a source code file (loaded with
the /C /MSB /AL or /PAS command line option switch), you will not need to
use the command line switch to view it the next time. BUZ saves the switch
information in the Quick Index.
BUZ Quick Index files are completely optional. For smaller text files on
fast computers, they are probably a waste of disk space. For very large
text files and/or on slower computers, you'll probably want to use them for
any files that you will want to view more than a time or two. You can
safely delete any Quick Index files any time - nothing is lost that cannot
be quickly and easily replaced. (Note: Quick Indexes are NOT read if the
file is on the A: or B: drive)
~ Example of File Preparation
---------------------------------
Below is an illustration of how "Prepared for BUZ" text files were intended
to be formatted.
+----------------------------------------------------------------+
| |
|~* Title |
| |
|~ Author Credits |
| |
| |
|~* Chapter 1 |
| |
| text |
| text |
| text |
| |
|~ Sub Section |
| |
| text |
| text |
| text |
| |
|~* Chapter 2 |
| |
| etc. |
+----------------------------------------------------------------+
~* Become a registered BUZ user!
--------------------------------
BUZ.EXE is Shareware. BUZ.EXE may be shared with others so long as it is
accompanied by BUZ.DOC and both files remain unaltered. BUZ is intended to
be a try-before-you-buy program. It is not FREEware. If you like BUZ and
use it - please register and pay for it.
NOTICE: BUZ.EXE may only be distributed in the United States and Canada,
unless you get written permission from the author - Dan Jincks. No
exceptions!
BUZ.EXE was developed to fill a text file viewing need in my other
shareware products. It turned out so well that I expanded it into a more
powerful general purpose program. If you are a paid registered user of any
other program by Dan Jincks, you need not pay for BUZ.EXE 1.10 - you are
automatically considered registered.
~ Basic User Registration
-----------------------------
If you are not a paid registered user of another program by Dan Jincks, and
you like and use BUZ.EXE 1.10, you are requested to register as a "basic
user" and pay a small fee. Your registration will be valid for any future
upgrades that you acquire on your own, until the author requests you to pay
an upgrade fee in the new version documentation. (not expected until
version 2.00 or later)
The fee is very small, and as such, the author offers no "extras" for
registering. If you like it as-is, please buy it.
~ Distributing User Registration
------------------------------------
If you are a Shareware or Freeware author, and would like to include
BUZ.EXE 1.10 with your product, you should register as a "distributing
user" and pay a modest "distributing user" registration fee. Then you may
distribute BUZ.EXE with your Shareware or Freeware - but BUZ.DOC must
accompany it in a very obvious manner. You may not alter BUZ.EXE or
BUZ.DOC, or attempt to hide its exit message and copyright notices. You
also must make it clear that BUZ.EXE is unregistered Shareware which
requires a separate "basic user" registration fee if used regularly.
The "distributing user" registration is more expensive than the "basic
user" registration. This is not the act of selling you a distributing
license. The extra charge is so that I can keep records and supply you
with upgraded versions as they become available. Record keeping and
shipping disks costs more than the "basic registration" fee. You are
encouraged to critique the way that BUZ.EXE does or does not fill your
needs. You are welcome to suggest improvements - and your ideas will be
given serious consideration in developing future improvements. Sending me
a copy of your applied usage of BUZ.EXE is optional, but recommended. This
is so that I can tailor improvements properly.
~ Commercial Distribution
-----------------------------
If you are interested it using BUZ.EXE 1.10 in or with a commercial
software product, I am flattered! Contact me directly to negotiate a very
reasonable arrangement. BUZ.EXE may NOT be utilized in any commercial
(paid for) products without a written contractual agreement with Dan
Jincks.
~ Retail Computer System and Software Dealers
-------------------------------------------------
You are welcome to distribute BUZ.EXE under the same conditions as the
"Distributing User" as outlined above. You may not charge your customers
for BUZ.EXE in any manner, or you are a "commercial distributor" and MUST
negotiate a contractual arrangement.
~ Shareware Distributors
----------------------------
You may distribute BUZ.EXE 1.10 in a way that is consistent with the other
Shareware products that you offer (ASP standards or better). If you
actually utilize BUZ.EXE for your marketing or distribution in any manner,
(e.g. Shareware catalog on disk) you must adhere to the rules of a
"distributing user", and register as such.
(To Print: Press "P" ENTER "Y")
~* Registration Form for BUZ.EXE V1.10
--------------------------------------
Basic User Registration ____________ first 5 computers - $5 per computer
6th to 100th computer - $4 per computer
over 100th computer - $3 per computer
Registration fee amounts should be based on the total number of computers
that BUZ.EXE is installed on, or used on, for any one address or company.
Distributing User _ (See the above conditions) __________ $30 per address
Type of registration ______________ Number ______ Amount ______________
Company Name ____________________________________________________________
Name ____________________________________________________________________
Address _________________________________________________________________
City, State and Zip _____________________________________________________
Where did you acquire BUZ? ______________________________________________
Send a Check or Money Order to: Dan Jincks
HCR 77, Box 155A
Annapolis, MO 63620 USA
Notice: BUZ.EXE is distributed AS-IS. The user accepts full
responsibility for the suitability and usage of BUZ.EXE. In no manner may
the author, Dan Jincks, be held liable for any damages that may allegedly
occur from the use of BUZ.EXE.
***********************************************************************
BUZ.EXE is dedicated to preserving our tree resources. Hopefully a few
trees will live a longer life (and continue purifying the air), due to the
capabilities of BUZ. Use BUZ to reduce your printer paper consumption
whenever you can.
Dan